BCI NET 2

home *** CD-ROM | disk | FTP | other *** search

/ BCI NET 2 / BCI NET 2.iso / archives / applications / wp / xes131.lha / XES / Docs / Paginate.man < prev next >

Wrap

Text File | 1994-11-09 | 25.5 KB | 626 lines

Paginate V1.00 User Manual Paginate V1.00 NAME Paginate - Can do both pagination and line numbering on files. SYNOPSIS Paginate <infile >outfile -F/K -f0/K -f1/K -ff/K -H/K -h0/K -h1/K -hf/K -N/K -t/K/N -b/K/N -l/K/N -r/K/N -p/K/N -T/S -F Default Format String for Footers -f0 Format String for Even Paged Footers -f1 Format String for Odd Paged Footers -ff Format String for Footer on First Page -H Default Format String for Headers -h0 Format String for Even Paged Headers -h1 Format String for Odd Paged Headers -hf Format String for Header on First Page -N Printf Style Format String for Line Numbering -t Top Line for Each Page -b Bottom Line for Each Page -l Left Margin for Headers and Footers -r Relative Right Margin for Headers and Footers -p Number of First Page -T Title Page COPYRIGHT Paginate Copyright (C) 1993 Fergus Duniho DESCRIPTION This program can do both pagination and line numbering on files. PAGINATION The pagination involves breaking a text file up into pages of equal length, and optionally marking each page with a header, a footer, or both. The headers and footers may contain the page number in various formats, as well as the time and date in various formats. They may also include any other text you want to put in them. You may choose different headers and footers for odd and even pages, as well as for the first page. You may also choose to have no header or footer on the first page, on odd pages, or on even pages. And you may choose to have the same footer or header on all pages. You may also choose to make the first page a title page. A title page has no headers and footers on it. Also, "Paginate" does not begin page numbering with a title page. And as far as the headers and footers for the first Page 1 Tue 27 Apr 1993 Paginate V1.00 User Manual Paginate V1.00 page are concerned, "Paginate" does not regard the title page as the first page. It considers it as the page prior to the first page. LINE NUMBERING The line numbering consists of printing a string with the line number in it at the beginning of each line. You may choose the format of the line number, and you may put other text in the line number string. The default is to do no line numbering. DEFAULT Paginate -F "@C- #d -" -H "" -N "" -l 9 -r 65 -t 4 -b 57 -p 1 USAGE Paginate reads from standard input and writes to standard output. So, to use it with files, you have to use redirection operators. The simplest way to use "Paginate" is without any arguments, and it may look like this: > Paginate <infile >outfile This will paginate a file such that you get one inch margins on all sides when you print it, or at least such that I will when I print it on a laser printer I have access to. It will also center the page number at the bottom of each page. And the page number will be in decimal form surrounded by a pair of hyphens like so: "- 1 -". You can change Paginate's behavior by specifying arguments. You may include arguments on the command line in any order. You must identify each argument with an identifier that begins with a hyphen. You can see these listed under SYNOPSIS. FORMAT STRINGS The arguments for headers, footers, and line numbering are format strings. The format strings may consist of text and conversion specifier. A conversion specifier is a bit of text that gets replaced by other text, such as a page number or line number. The format strings for headers and footers may also include formatting codes. CONVERSION SPECIFIERS FOR LINE NUMBERING Paginate uses printf() for line numbering. Since Paginate uses the line number as the only other argument in printf() besides the format string, the format string for line numbering may include only one conversion specifier. This conversion specifier must be one which turns an Page 2 Tue 27 Apr 1993 Paginate V1.00 User Manual Paginate V1.00 integer into a string. Here are the allowable conversion specifiers for line numbering: %c - unsigned char %d, %i - decimal integer %o - octal integer %u - unsigned decimal integer %x, %X - unsigned hexadecimal integer Some of these, such as %c, may be useless for page numbering, but they're provided anyway, since printf() provides them. If you know how many lines your document has, your output will look best if put a number between the '%' character and the character that follows it. For example, "%3d" will print all your line numbers in a space with a width of 3. See a description of printf() in any book on C for more details. CONVERSION SPECIFIERS FOR HEADERS AND FOOTERS Paginate does not use printf() for headers and footers. Instead, it uses strftime() plus some other conversions that I wrote myself. This is because I wanted roman numeral page numbers, and printf() does not provide this feature. For the headers and footers, Paginate accepts conversion specifiers for the date, the time, and the page number. The conversion specifiers it uses for the date and time are the same as those used by the C function strftime(). Depending upon what compiler was used to compile the version of Paginate you have available, the conversion specifiers for date and time may vary. As long as the compiler adhered strictly to the ANSI standard, here are the conversion specifiers you may expect to use for the date and time: %a - abbreviated weekday name %A - full weekday name %b - abbreviated month name %B - full month name %c - date and time %d - day of the month %H - hour of the 24-hour day %I - hour of the 12-hour day %j - day of the year, from 001 %m - day of the month, from 01 %p - AM/PM indicator %S - seconds after the minute Page 3 Tue 27 Apr 1993 Paginate V1.00 User Manual Paginate V1.00 %U - Sunday week of the year, from 00 %w - day of the week, from 0 for Sunday %W - Monday week of the year, from 00 %x - date %X - time %y - year of the century, from 00 %Y - year %Z - time zone name, if any According to the tests I have done on the strftime() function in DICE, which I compiled the Amiga version with, "%W" might mean something else, since it gives a value of 1 for April 27. The others seem to work as expected. Paginate also understands the following conversion specifiers for the page number: #d - page number in decimal #o - page number in octal #x - page number in hexadecimal #b - page number in binary #r - page number in lowercase roman numerals #R - page number in uppercase roman numerals Because paginate uses the number sign (#) and percent sign (%) for conversion specifiers, and because it uses the at sign (@) for formatting codes (see below), it also recognizes the following conversion specifiers: %% - percent character % ## - number sign (pound sign, octothorp, etc.) # @@ - at sign @ Unlike the conversion specifiers for line numbering, the conversion specifiers for headers and footers do not have all the features that printf() conversion specifiers have. FORMATTING CODES Paginate uses formatting codes to position text in the headers and footers. It understands the following formatting codes: @L - left align text @C - center text @R - right align text If you do not use any formatting codes, the default behavior will be to left align the text. You can use all Page 4 Tue 27 Apr 1993 Paginate V1.00 User Manual Paginate V1.00 three of these formatting codes within a format string. This allows you to have some text left aligned, some centered, and some right aligned. The scope of any formatting code extends only up until the end of the string or the next formatting code. So, in something like "@C#R@Ltitle@Rauthor", you get a header or footer that looks something like this: title I author Paginate also recognizes formatting codes which consist of an at sign (@), an optional minus sign (-), and a lowercase hexadecimal digit. These are used for placing text at specific positions in headers and footers. They work by adding to or substracting from the current position. For example, "@R@-a" will begin text ten places to the left of the right margin. "@C@0" will begin a piece of text right at the center. They may also be used more than once together. For example, "@L@9@f" will begin text at position 25, because "@L" sets the position to 1, "@9" adds nine to that, and "@f" adds fifteen more. Please note that "@C@0text" will not work the same as "@Ctext". Both "@C" and "@R" work by determing the length of the text segment that follows, and they use that length to determine a cursor position to begin the text at. When another formatting code immediately follows "@C" or "@R", Paginate calculates a position for a string whose length is zero. Thus, "@C@0text" begins the word "text" at the center, whereas "@Ctext" centers the word "text". EXAMPLES > Paginate <infile >outfile -F "" -H "@RPage ###d" This turns off all footers, and it puts on each page a header that includes the page number on the right side. The right aligned text for the header on the first page looks like this: "Page #1". > Paginate <infile >outfile -f0 "" -f1 "" -hf "" -H "Title@RPage#d" This turns off the footer for odd and even pages, but not for the first page. It sets a default value for the header, and it turns the header off for the first page. So, it puts the page number in a footer on the first page, and it puts the page number in a header on all subsequent pages. Each header has the word "Title" left aligned and the page number right Page 5 Tue 27 Apr 1993 Paginate V1.00 User Manual Paginate V1.00 aligned. > Paginate <infile >outfile -l 1 -F "" -H "Page #R" -h0 "@RPage #R" This sets the left margin to 1, turns off the footer, and prints alternate headers on odd and even pages. On odd pages, it left aligns the page number, and on even pages, it right aligns the page number. > Paginate <infile >outfile -T -F "" -ff "@CPage #r" -h0 "Page #r" -h1 "@RPage #r" This creates a title page, on which there are no headers or footers. It counts the second page as page #1, and it centers the page number in a footer for that page. It puts the page number in a header on all subsequent pages. It left aligns the page number on even pages and right aligns it on odd pages. It prints the page number in lowercase roman numerals. > Paginate <Paginate.man >P.man -F "Page #d@R%a %d %b %Y" -H "Paginate V1.00@CUser Manual@RPaginate V1.00" These are the parameters I chose to paginate this manual with. Just take a look at the headers and footers in this manual to see the results. > Type *.h | Paginate >headers -N "%3d " -H "Header Files@RPage #d" -F "" -l 5 -r 70 This example shows how you can use Paginate on multiple files. By typing a bunch of files to standard output with 'type', you can use a pipe to redirect the output to Paginate. It puts a header on each page, and it numbers each line. It aligns the header with the text rather than with the line numbers. (Changing the 5 after '-l' to a 1 would align the header with the line numbers.) DETAILS Paginate gets the time only once. This means that it will not print different times on different pages. Paginate does not begin page numbering with the title page. So, if you include a title page, and you want page numbering to start on page number 1, the first page number should be set to 1 rather than to 0. This convention is different from what I have seen on ProWrite. Paginate puts a formfeed at the end of each page. Page 6 Tue 27 Apr 1993 Paginate V1.00 User Manual Paginate V1.00 Whenever Paginate finds a formfeed in your input file, it recognizes that it has come to the end of a page. If it is supposed to put a footer on that page, it inserts linefeeds until it reaches the bottom of the page, inserts the footer, and then inserts a formfeed. If it isn't supposed to put a footer on that page, it just inserts a formfeed and goes on to the next page. Paginate puts the header on the line indicated by "-t", and it puts the footer on the line indicated by "-b". When a page doesn't expect a header or footer, Paginate puts a line of text where the header or footer would go. Thus, a page with a header and footer on it has fewer lines of text than the same page without the header and footer. Paginate always separates each header and footer from the text by a blank line. The length of any format string should at no time, which means after conversions as well as initially, be longer than the value set by "-r", which is 65 by default. Rather than specifying the value of the right margin, "-r" specifies how far the right margin is from the left margin. This is because Paginate never used the right margin for anything but finding the difference between the left and right margins. This gives you the added advantage of being able to play with the left margin value without regularly changing the right margin value to keep the difference the same. The leftmost left margin is 1, not 0. The topmost top line is 1, not 0. All the conversion specifiers and formatting codes are case sensitive. For example, "@C" instructs Paginate to center some text, whereas "@c" instructs Paginate to place text 12 spaces to the right of its current position in a header or footer. COMPILING Paginate is written completely in ANSI C. Although I wrote it on the Amiga, it does not use any Amiga specific features. You should be able to compile it on any machine with an ANSI C compiler. Please note that the Amiga version of GCC 2.3.3 has a bug which causes this program to go into an infinite loop. I Page 7 Tue 27 Apr 1993 Paginate V1.00 User Manual Paginate V1.00 don't know if other versions of GCC have this same problem. HISTORY I first needed a pagination program when I began writing my essays with dme instead of with my word processor. I preferred dme because it was faster and much more customizable, but it didn't have all the nice features that my word processor had, including pagination. My first pagination program was an ARexx script called Paginate.dme. This would put some lines at the beginning of a page, and it would center the line number at the bottom of the page. It would let me control such parameters as first page number and number of lines per page. When I began writing XDMD, the soon to be released successor of DMD, I decided that I wanted something better. I downloaded Pager to see if it would suit my needs, and it didn't. So I wrote this program, which is much more powerful than both Paginate.dme and Pager. In my opinion, it completely replaces both. I originally started writing it in C++, since I want to learn that language. But I found that GCC has a bug in strftime(). So I converted it to C and used DICE. DISTRIBUTION You may freely distribute this program by any non-commercial means as long as the source code, this manual, and the program are all included together, and no one but myself has made any changes. It is OK to recompile the source code with another C compiler and to redistribute it with the new executable, the source code, and this manual. You might do this, for example, to distribute it on machines other than the Amiga. If you do so, place a note about what you did in a separate text file. This program may not be distributed with any commercial product without my written permission. This program may not be sold by anyone. But it may be included on disks of freely distributable software which sell for no more than what Fred Fish charges for his disks, and which contain as much freely distributable software as they can hold. Fred Fish and DevWare are permitted to include this program on their disks of freely distributable software. Page 8 Tue 27 Apr 1993 Paginate V1.00 User Manual Paginate V1.00 DISCLAIMER You use this product at your own risk. I, Fergus Duniho, offer no guarantees that it will suit any of your purposes. I do not guarantee the behavior of this program in any way, and I cannot be held accountable for any misfortunes that result from the use of this program. SHAREWARE/FREEWARE This program is shareware for some people and freeware for others. For those who write freeware or public domain software for the Amiga, this is freeware, for they contribute their efforts to a pool that we become richer by drawing from. For sysops, this is freeware, for they volunteer their time and services to make computing all that much richer. For students and other poor people, this is freeware, since they can't afford to pay shareware fees for all the shareware they might use. For people who don't live in Canada or the United States, this is freeware, because I don't want to go through the bother of cashing checks from foreign banks or exchanging foreign money. But I live close enough to Canada that Canadian money isn't a problem. For crooks, pirates, and other immoral people, this is freeware, since they wouldn't pay the shareware fee anyway. For authors of shareware, who do not also write freeware or public domain software, this is shareware, for they ask people to pay for their programs, and so I ask the same of them. For well-to-do professionals, who do not make unpaid contributions to the computing community with programs or services, this is shareware. For Objectivists, this is shareware, for a good Objectivist would pay the shareware fee. For individuals, the shareware fee is $10.00 in American money or $15.00 in Canadian. For institutions, churches, and mainframes, the shareware fee is $20.00 in American money or $30.00 in Canadian. For the military, the shareware fee is $500.00 in American Page 9 Tue 27 Apr 1993 Paginate V1.00 User Manual Paginate V1.00 money or $750.00 in Canadian, since the military wouldn't pay the shareware fee unless it were exorbitantly high. You will get nothing in return for your shareware fee except a clean conscience and the knowledge that you have made me happy by showing your appreciation for my work. ETHICAL USE You may not use Paginate for any unethical purpose unless you pay ten times the shareware fee with clean, honestly earned money. Stolen or extorted money will not do. Unethical uses include the pagination of the following sorts of documents: Propaganda Leaflets for Religious Cults Hate Groups Racial Pride Groups Communism Fascism Nazism Socialism Nationalism Advertisements Annoying letters asking for money Chain letters Smut that degrades women Death threats Ransom notes Besides these, there may be unethical uses I haven't thought of. Ethical uses may include the pagination of love letters, homework, manuals, programs, newsletters, and other harmless and inoffensive material. AUTHOR The one, the only, the incomparable and humble Fergus Duniho. You may reach me at the following email address: Internet: fdnh@troi.cc.rochester.edu If you live in the Rochester calling area, you may also send me email on FileWorks, the best Amiga BBS in the area. Page 10 Tue 27 Apr 1993 Paginate V1.00 User Manual Paginate V1.00 You can send all shareware fees to me at Fergus Duniho 1095 Genesee St. Rochester, NY 14611 Look for these other fine Amiga software products by me: The Duniho and Duniho Life Pattern Indicator (DDLI) XDME Macros by Duniho (XDMD) AlphaSpell - A command line spelling checker And if you don't use an Amiga, look for the IBM version of the DDLI. It's available from the SimTel Software Repository. Page 11 Tue 27 Apr 1993